'\"
'\" Copyright (c) 1998-2000 by Ajuba Solutions
'\" All rights reserved.
'\" 
'\" RCS: @(#) $Id: httpd.1,v 1.2 2004/03/09 11:07:31 coldstore Exp $
'\" 
.so man.macros
.TH tclhttpd 1 "" TclPro "TclPro Applications"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
tclhttpd \- Tcl Web Server

.SH SYNOPSIS
\fBtclsh httpd.tcl\fR ?\fIoptions\fR?

.SH OPTIONS
.PP
.IP "\fB\-help\fR" 15
Displays usage information, then exit without doing anything.
.IP "\fB\-config\fR \fIfilename\fP" 15
Name of the configuration file (e.g. tclpro/bin/tclhttpd.rc).
.IP "\fB\-main\fR \fIfilename\fP" 15
Name of the per-thread main script (e.g. tclpro/bin/httpdthread.tcl).
.IP "\fB\-docRoot\fR \fIdirectory\fP" 15
The root directory of your web pages (e.g., tclpro/tclhttpd/htdocs).
.IP "\fB\-port\fR \fIvalue\fP" 15
HTTP listening port.  Defaults to 8015.
.IP "\fB\-host\fR \fIvalue\fP" 15
The hostname for the HTTP listening socket.
.IP "\fB\-ipaddr\fR \fIvalue\fP" 15
Interface the server should bind to.
.IP "\fB\-webmaster\fR \fIemail\fP" 15
Email contact for webmaster.
.IP "\fB\-uid\fR \fIuserid\fP" 15
User name or ID for server process user ID.
.IP "\fB\-gid\fR \fIgroupid\fP" 15
Group name or ID for server process group ID.
.IP "\fB\-threads\fR \fInum\fP" 15
Run with \fInum\fP worker threads.
Requires a thread safe Tcl shell.
.IP "\fB\-library\fR \fIdirectory\fP" 15
Directory to add to the auto_path.
.IP "\fB\-verbose\fR" 15
Causes extra print statements during startup.
.BE

.SH DESCRIPTION
.PP
TclHttpd is a simple, extensible, embeddable Web Server.
The best source of documentation is in HTML distributed with
the server.
.PP
To start the server, simply run the httpd.tcl
script with \fItclsh\fP or \fIwish\fP.
For example, this starts the server on the standard
Web server port, 80.
.DE
tclsh <installdir>/bin/httpd.tcl -port 80
.DE
Note that you must start the server as root if you use port numbers
less than 1024 on UNIX systems.  If you want the server process to
run under a different user than root, which is strongly recommended,
then use the \fB-uid\fP and \fB-gid\fP options.  This way the server
can start as root, open the socket, and then switch
to a less privileged account.

.SH "CONFIGURATION AND CUSTOMIZATION"

The main script depends on a per-thread Tcl script,
httpdthread.tcl, and a configuration file, tclhttpd.rc. 
These have configuration settings and the start up code
for the web server.
.PP
The configuration file can be used
to set the port, user ID, and other values described in
the Options list above.
You can configure additional features
such as log file location, and more, by editting the
configuration file.
There is an explanation about each option, so you can
make a copy of the configuration file and try out new settings.
.DS
tclsh httpd.tcl -config myserver.rc
.DE
.PP
If you plan to extend Tcl Httpd with your own code,
you may need to add initialization code to
bin/httpd.tcl and bin/httpdthread.tcl.  This code is
typically a "package require" for your module and one
or two calls to initialize it.
For example, this code the httpdthread.tcl enables
a /debug URL implementation that lets you examine the
state of the server.
.DS
package require httpd::debug
Debug_Url /debug Debug
.DE
.PP
The web server should have access to any Tcl package installed
along with your Tcl installation.  Consult the on-line HTML 
documentation for a more indepth discussion of programming the server.

.SH "WEB PAGE TEMPLATES"
.PP
TclHttpd supports a flexible template system that embeds Tcl code into
your HTML pages.  The Web Server processes the Tcl, which typically
generates bits and pieces of your HTML page, and delivers the result
to the client transparently.  You can cache the results of processing
your templates, or you can have pages that are processed dynamically
on each access.
.PP
Any page that ends in ".tml" is treated like an HTML+Tcl template page.
The Web Server uses the Tcl \fBsubst\fP command to replace
commands within brackets, [ and ], and variable references,
like $Phone, with their value.  Backslash processing is also done.
The main thing you need to watch out for is putting literal dollar
amounts in your templates.  You'll need to protect your $ with
a backslash:
.DS
The price is \\$10.00.
.DE
The ".tml" files in the sample htdocs directory structure should
give you examples to work from.
.PP
Try to limit the Tcl code in your pages to simple procedure calls,
and put the procedure definitions in per-directory files named
".tml".  The name of this file is confusing:
each directory can contain a file
named "dot-t-m-l" (\fP.tml\fP) that should contain Tcl code.
These files are automatically loaded before any templates in
that directory (or subdirectories) is processed.
.PP
For example, first create a new directory of the htdocs
directory that comes with TclHttpd.
.DS
mkdir htdocs/mystuff
.DE
Next, put the following into htdocs/mystuff/.tml
.DS
package require htmlutils

# A procedure to format the date the way you like it
proc MyDate {{seconds {}}} {
    if {[string length $seconds] == 0} {
	set seconds [clock seconds]
    }
    return [clock format $seconds -format "%B %m, %Y"]
}
# Some page settings
set bgcolor pink
.DE
Now, any page in the htdocs/mystuff directory can use the
\fBMyDate\fP procedure in a template.
Finally, put the following into htodcs/mystuff/index.tml
.DS
<title>My Stuff</title>
<body text=black bgcolor=$bgcolor>
<h2>My Stuff</h2>
[MyDate]
<br>
Page content here.
<p>
Send email to [Mailto [Doc_Webmaster]].
.DE
The \fBbgcolor\fP variable is set in the .tml file and used
in the BODY tag.
The \fBMailto\fP is part of the \fBhtmlutils\fP package that
was required by the .tml file.
The \fBDoc_Webmaster\fP procedure is built into TclHttpd.
The \fPMyDate\fP procedure was added by you, and
is shared by any page in or below the htdocs/mystuff directory.

.SH KEYWORDS
Web Server, HTTP, TclHttpd
